Content

 Introduction
 Commands in Detail
 Functions to Transform Floating Point Numbers into Strings and Vice Versa

Introduction

The Extension Library expands the command set of Omikron Basic by commands that are not contained in the standard command set but that are required or at least useful for the creation of programs for the MacOS. In order to use the Extension Library it must be loaded into the program in the editor with the menu option 'Merge LIBRARY'. It is important to remember calling an 'Extension_Init' at the beginning of the program and an 'Extension_Exit' at its end.

Note: All functions without any postfix are of the long integer type (%L). If you have defined another default type in your editor, the postfix "%L" has to be added to the function names.

Commands in Detail

Extension_Init
This procedure must be called once before any other commands are used.

Extension_Exit
This procedure is called if use of the library functions has been concluded.

Error_Messages F
If an error occurs in your program during runtime (e.g., if an attempt was made to open a file that does not exist), an error message is then usually issued by Omikron Basic and output to an alert box. This behavior is certainly very useful during the program's development time - however, it is more likely rather disturbing once the program has been completed. For this reason, the output of error messages can be turned off with this procedure.

F=0 : Error messages off; otherwise, error messages on.

However, in case a fatal error occurs (e.g., if too little BASIC memory is available), which makes a continuation of the program impossible, Omikron Basic will always issue a message and terminate the program as well.

Set_Help(Tc)
This procedure defines, which key should be used for ON HELP GOSUB. The keyboard code must be applied for Tc. The default value is $69, which corresponds to function key 13 (F13). An overview of the keyboard codes can be found in "Inside Macintosh, Toolbox Essentials" and in the appendix 'Virtual Key Codes'.

Set_Sleep(S)
This procedure sets the sleep parameter, which Omikron Basic passes to the MacOS at every call of a WaitNextEvent (see also 'The Omikron Basic Output Windows' and 'New Compiler Control Words'). The sleep parameter determines how much CPU time will be allotted to other programs. The default value is 1; a higher number slows down the program, instead, however, this leaves more processor time for other programs running parallel.

Set_Tab(T)
This procedure sets the tabulator, which is used for PRINT and LPRINT. The default value is 8.

Fill_Input_Buffer(F$,C)
The INPUT buffer is loaded with the string F$, the cursor is set to position C, starting at the beginning of INPUT. This command makes it possible to pre-set an input value for INPUT statements, which must then only be confirmed with [Return] if necessary. Since the INPUT buffer is also used for other tasks, this procedure should always be called immediately before the actual INPUT command.

FN Get_Created_Dirid
If a new directory is created using MKDIR, the identification number of this directory may be received if this function is called directly afterwards.

Get_Def_Dir(R Vrefnum%,R Dirid,R Volname$,R Errnum)
This procedure returns the volume reference number, the directory identification number, and the volume name of the default path. If necessary, Errnum contains an error number.

Get_Cur_Dir(R Vrefnum,R Dirid)
This procedure returns the volume reference number and the directory identification number of the current path.

Get_System_Folder(Type,R Vrefnum,R Dirid,R Os_Err)
This procedure serves to determine the volume reference number and the directory identification number of the system folder and all subfolders in the system folder.
The folder type has to be passed in Type. The following elements are possible:

Type = CVIL("amnu") : Apple Menu Items
Type = CVIL("ctrl") : Control Panels
Type = CVIL("Desk") : Desktop Folders
Type = CVIL("extn") : Extensions
Type = CVIL("font") : Fonts Folder
Type = CVIL("pref") : Preferences Folder
Type = CVIL("prnt") : Print Monitor Documents
Type = CVIL("strt") : Startup Items
Type = CVIL("macs") : System Folder
Type = CVIL("temp") : Temporary Items
Type = CVIL("trsh") : Single User Trash
Type = CVIL("empt") : Shared Trash on Net

Os_Err may have the following values when returned:

Os_Err=0 : No error.
Os_Err=-43 : The indicated type was not found.
Os_Err=-48 : A file was found instead of a folder.

FN Get_Vrefnum(Fsspec$)
This function returns the volume reference number if a FileSpecificationRecord is passed.

FN Get_Dirid(Fsspec$)
This function returns the directory identification number if a FileSpecificationRecord is passed.

FN Get_Filename$(Fsspec$)
This function returns the file name if a FileSpecificationRecord is passed.

FN Get_Font_Number(Name$)
This function returns the number of a font if its name has been passed to the function (e.g., Monaco, Courier, VT100).

FN Get_Fsspec$(Vrefnum,Dirid,Filename$)
If a volume reference number, a directory identification number, and a file name is passed to this function, such a FileSpecificationRecord is returned as it is e.g., needed for OPEN. Vrefnum and Dirid can also be zero. However, in that case Filename$ can either contain a complete path or a partial path with a preceeding colon or a pure file name without a preceeding colon, with the latter two considered to be based on the current path. Thus, if you pass a partial path you have to write a colon in front of all other characters.

FN Get_File_Count
With this function it is possible to find out, how many bytes have actually been read or written, for example, in the case of PUT or GET.

FN Get_File_Type(Fsspec$)
This function returns the file type (e.g., "TEXT", "PICT" ...) of the file specified by Fsspec$. The result of this function is a long integer number. In order to receive a string, the BASIC function MKIL$ has to still be applied to the long integer number

FN Get_File_Creator(Fsspec$)
This function returns the file creator (e.g., "OmBa" ...) of the file specified by Fsspec$. The result of this function is a long integer number. In order to receive a string, the BASIC function MKIL$ has to still be applied to the long integer number.

FN Get_Finder_Flags(Fsspec$)
This function can be used to determine which finder flags have been set using the file specified by Fsspec$. Most of the finder flags are used internally. Thus, only those flags are listed below, which are of interest for the programmer and may be modified as well. Those programmers who would like to know more about the significance of the remaining flags, please read the appropriate sections in  "Inside Macintosh, Toolbox Essentials."

Bit 14 : The file is invisible, thus it is displayed neither on the desktop nor in the file select box.
Bit 13 : The file has a "BNDL" resource. Such a resource is required to assign specific icons to the files.
Bit 12 : Neither the icon nor the name can be modified from the Finder.
Bit 11 : The file is a so-called "stationery pad."  To describe this term in more details would surpass the available space here. More details can be found in "Inside Macintosh, Toolbox Essentials."
Bit 10 : The file has a "customized icon."
Bit 6 : The file is a program, which can be used simultaneously by several users within a network.

Note: The finder flags can also be applied to directories. Insofar as the result might not have any practical significance, these finder flags should be considered reserved and thus not be modified.  

Set_File_Type([Fsspec$,]Filetype)
When creating a new file (e.g., using OPEN "O"), the file type number, which was previously set using this procedure, is assigned to the file. For example, Set_File_Type(CVIL("TEXT") causes all subsequently created files to be of the type 'TEXT', that is, they are pure ASCII files. The appendix lists the most important pre-defined file types.
When using a syntax with 2 parameters, it is possible to pass a FileSpecificationRecord in Fsspec$, which then modifies the type of the file thusly determined.
A more detailed description of the previously mentioned terms can be found in "InsideMacintosh, Files."

Set_File_Creator([Fsspec$,]Creator)
When creating a new file (e.g., using OPEN "O"), the CreatorIdentificationNumber, which was previously set using this procedure, is assigned to the file. 
When using a syntax with 2 parameters, it is possible to pass a FileSpecificationRecord in Fsspec$, which then modifies the creator of the thusly determined file.

Set_Finder_Flags(Fsspec$,Flags)
This procedure allows the modification of the so-called finder flags. This requires that a FileSpecificationRecord is passed in Fsspec$, which specifically determines the file containing the to be modified flags. The significance of the indivdual bits is described under FN Get_Finder_Flags.

FN Get_Quick_Draw
This function returns a pointer to the QuickDrawGlobals. "Inside Macintosh, Imaging with QuickDraw " features a precise description of this structure.

FN Get_G_World_Ptr
This function returns a pointer to the offscreen graphics world used for buffering the uppermost output window of Omikron Basic. The structure is described in " Inside Macintosh, Imaging with QuickDraw."

FN Get_G_World_Ptr(S)
This function returns a pointer to the offscreen graphics world used for buffering the output window of Omikron Basic, which has been opened with SCREEN S. The structure is described in "Inside Macintosh, Imaging with QuickDraw."

FN Get_Window_Ptr
This function returns a pointer to the window pointer of the output window of Omikron Basic, which has been opened with SCREEN S. The structure is described in " Inside Macintosh, Imaging with QuickDraw."

Get_Window_Offset(Screen_Nr,R X_Offset,R Y_Offset)
If you are working with Omikron Basic output windows and would like to directly output to the real windows, you have to know which part of the virtual screen buffered in memory is currently displayed in the window because this is dependent on the position of the scroll bars.
The procedure Get_Window_Offset calculates the offset using the position of the scroll bars, which is assigned to the left, upper inside corner of the real window on the virtual screen and returns these values in X_Offset and Y_Offset.

Set_Window_Title(T$)
This procedure sets the title of the uppermost Omikron Basic output window to T$.

Get_Indexed_Color(Index,R Red,R Green,R Blue)
This procedure returns the red, green, and blue components of a color from the internal Omikron Basic color map, whose index is passed. Red, green and blue can take values between 0 and 65535.#

Set_Indexed_Color(Index,Red,Green,Blue)
This procedure sets the red, green, and blue component of a color in the internal Omikron Basic color map, whose index is passed. Red, green, and blue must have values between 0 and 65535.

Set_Pen_Size(Width,Height)
This procedure sets the width and height of the drawing pen used e.g., for DRAW or BOX. It corresponds to LINE WIDTH except that in this case, width and height can take different values.

Set_Roundings(X,Y)
This procedure defines the rounding of the corners during use of RBOX and PRBOX. X and Y are the semi-axes of an ellipse being adapted to the rounding.

Set_Scroll_Parameter(X,Y)
This procedure defines the number of the pixels by which the content of the output windows is to be moved when clicking on the scroll arrows. X represents the horizontal and Y the vertical direction. The default setting is 8 for X and 16 for Y.

Set_Text_Mode(Mode)
This procedure sets the linking mode as used in the case of MODE, only difference is that this procedure is especially for TEXT commands.

Set_Text_Size(Size)
This procedure corresponds to the command TEXT HEIGHT, thus adjusts the size of characters output with the TEXT commands.

Set_Text_Font(Font_No)
This procedure selects the font to be used for TEXT commands.

Set_Text_Face(Face)
This procedure corresponds to the command TEXT STYLE, thus adjusts the font style of characters output with the TEXT commands.

Set_Text_Fore_Color(Index)
This procedure corresponds to the command TEXT COLOR, thus sets the display foreground color used for TEXT commands to the color assigned to the index.

Set_Text_Back_Color(Index)
This procedure sets the background color used for TEXT commands to the color assigned to the index.

Set_Print_Mode(Mode)
This procedure sets the linking mode the same way as in the case of MODE, only difference is that this procedure is especially for PRINT and INPUT commands.

Set_Print_Size(Size)
This procedure sets up the size for those characters that are output with PRINT and INPUT commands.

Set_Print_Font(Font_No)
This procedure selects the font to be used for PRINT and INPUT commands.

Caution: The PRINT and INPUT commands function only correctly if non-proportional fonts are being used, that is, fonts where all letters are equally wide. For all the existing default fonts, this is true only for ''Monaco (Font_No=4)' and 'Courier (Font_No=22)''. Starting with system 7.6, 'VT100' is still available as well.

Set_Print_Face(Face)
This procedure approximately corresponds to the command TEXT STYLE. However, the setting is only valid for PRINT and INPUT commands.

Set_Print_Fore_Color(Index)
This procedure sets the foreground color used for PRINT and INPUT commands to the color assigned to the index.

Set_Print_Back_Color(Index)
This procedure sets the background color used for PRINT and INPUT commands to the color assigned to the index.
Note: This command can also be used to set the background color for the Omikron Basic output windows.

Set_Lprint_Mode(Mode)
This procedure sets the linking mode the same way as in the case of MODE, only difference is that this procedure is especially for LPRINT commands.

Set_Lprint_Size(Size)
This procedure adjusts the size of characters output with the LPRINT commands.

Set_Lprint_Font(Font_No)
This procedure selects the font to be used for LPRINT commands.

Caution: The PRINT and INPUT commands function only correctly if non-proportional fonts are being used, that is, fonts where all letters are equally wide when tabulator functions are being used. For all the existing default fonts, this is true only for ''Monaco (Font_No=4)' and 'Courier (Font_No=22)''. Starting with system 7.6, 'VT100' is still available as well.

Set_Lprint_Face(Face)
This procedure approximately corresponds to the command TEXT STYLE. However, the setting is only valid for PRINT and INPUT commands.

Set_Lprint_Fore_Color(Index)
This procedure sets the foreground color used for LPRINT commands to the color assigned to the index.

Set_Lprint_Back_Color(Index)
This procedure sets the background color used for LPRINT commands to the color assigned to the index.

Lprstldialog(R Button)
This procedure calls the dialog box 'PrStlDialog' of the printer driver. If the box was exited with OK, Button=1, otherwise 0. The possibility to call this dialog box should be incorporated into the program, otherwise any subsequent printouts will use only the unspecified default values.

Lprjobdialog(R Button)
This procedure calls the dialog box 'PrJobDialog' of the printer driver. If the box was exited with OK, Button=1, otherwise 0. This dialog box should be called unconditionally before every printout since the user still has the opportunity to adjust important settings in this dialog box. For example, which pages should even be printed, whether a preview is requested (not possible for every printer), which resolution should be used for the printout, and a few additional preference settings.

FN Microseconds#
This function returns the time, elapsed since system start up. Note, that this function is of type double float. It is similar to the BASIC function TIMER, but allows time measurements of much higher pecision, because the counter is incremented every millionth second instead of every 1/200.

FN Ser_Get_Buf (Channel)
This function returns the number of characters available in the buffer of the serial port. The channel has to be opened previously via OPEN "P",Channel and/or OPEN "V",Channel.

Ser_Reset (Channel,In_Out,Baud,Parity,Data_Bits,Stop_Bits)
This procedure allows the configuration of the serial port, which has been opened previously via OPEN "P",Channel and/or OPEN "V",Channel. In_Out determines, whether the settings should be made for input or output:
In_Out=1 : output
In_Out=2 : input
In_Out=3 : output and input

Whith 'Baud' you can set the transfer rate in bits per second. Parity, Data_Bits, and Stop_Bits are self-explaining.

Functions to Transform Floating Point Numbers into Strings and Vice Versa

The floating point number format, which was used by Omikron Basic for Atari computers differs from the one used for the PowerPC. In order to avoid a continual format conversion accompanied by the corresponding performance loss, the new Omikron Basic was changed to correspond to the PowerPC format (see also the chapter 'Differences Compared to the Atari Version').

In order to facilitate the conversion of older programs, there are four functions in the Extension Library, which emulate the behavior of the old Omikron Basic functions.

FN CVS#(Single$)
These function converts a 6-byte string of the old format into a double floating number.

Caution: Since the new format has a lesser value range than the old, errors may occur in the case of very small and/or very large numbers.

FN CVD#(Double$)
These function converts a 10-byte string of the old format into a double floating number.

Caution: Since the new format has a lesser value range than the old, errors may occur in the case of very small and/or very large numbers.

FN MKS$(Number)
This function converts a number into a 6-byte long string of the old format.

FN MKD$(Number)
This function converts a number into a 10-byte long string of the old format.